jest-each

What is jest-each?

The jest-each npm package is an extension for Jest, a popular JavaScript testing framework. It allows you to run a single test multiple times with different sets of data, making it easier to test functions with various inputs and expected outputs.

What are jest-each's main functionalities?

Parameterized Tests

This feature allows you to run the same test with different sets of data. In this example, the test checks if the sum of two numbers equals the expected result for multiple sets of inputs.

const each = require('jest-each').default;

each([ [1, 1, 2], [1, 2, 3], [2, 1, 3] ]).test('adds %d and %d to equal %d', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

Table-Driven Tests

This feature allows you to define test cases in a tabular format, making it easier to read and manage multiple test cases. The example demonstrates how to use a table to test the addition of two numbers.

const each = require('jest-each').default;

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.test('adds $a and $b to equal $expected', ({ a, b, expected }) => {
  expect(a + b).toBe(expected);
});

Other packages similar to jest-each

mocha

Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser. It allows for flexible and accurate reporting, while mapping uncaught exceptions to the correct test cases. Mocha can be used with various assertion libraries, and while it doesn't have built-in support for parameterized tests like jest-each, it can achieve similar functionality with the help of additional libraries like 'mocha-each'.

ava

AVA is a test runner for Node.js with a concise API, detailed error output, and process isolation. It supports running tests concurrently, which can lead to faster test execution. AVA supports parameterized tests through its 'test.each' method, similar to jest-each, making it a good alternative for those looking for a minimalistic and fast testing framework.

tape

Tape is a minimalist JavaScript test runner that works in both Node.js and the browser. It does not have built-in support for parameterized tests, but you can achieve similar functionality by writing loops within your test cases. Tape is known for its simplicity and ease of use, making it a good choice for smaller projects or those who prefer a lightweight testing solution.

README

jest-each

Jest Parameterised Testing

---

A parameterised testing library for Jest inspired by mocha-each.

jest-each allows you to provide multiple arguments to your test/describe which results in the test/suite being run once per row of parameters.

Features

• .test to runs multiple tests with parameterised data
  • Also under the alias: .it
• .test.only to only run the parameterised tests
  • Also under the aliases: .it.only or .fit
• .test.skip to skip the parameterised tests
  • Also under the aliases: .it.skip or .xit or .xtest
• .test.concurrent
  • Also under the alias: .it.concurrent
• .test.concurrent.only
  • Also under the alias: .it.concurrent.only
• .test.concurrent.skip
  • Also under the alias: .it.concurrent.skip
• .describe to runs test suites with parameterised data
• .describe.only to only run the parameterised suite of tests
  • Also under the aliases: .fdescribe
• .describe.skip to skip the parameterised suite of tests
  • Also under the aliases: .xdescribe
• Asynchronous tests with done
• Unique test titles with printf formatting:
  • %p - pretty-format.
  • %s- String.
  • %d- Number.
  • %i - Integer.
  • %f - Floating point value.
  • %j - JSON.
  • %o - Object.
  • %# - Index of the test case.
  • %% - single percent sign ('%'). This does not consume an argument.
• Unique test titles by injecting properties of test case object
• 🖖 Spock like data tables with Tagged Template Literals

---

• Demo
• Installation
• Importing
• APIs
  • Array of Rows
    • Usage
  • Tagged Template Literal of rows
    • Usage

Demo

Tests without jest-each

Tests can be re-written with jest-each to:

.test

.test with Tagged Template Literals

.describe

Installation

npm i --save-dev jest-each

yarn add -D jest-each

Importing

jest-each is a default export so it can be imported with whatever name you like.

// es6
import each from 'jest-each';

// es5
const each = require('jest-each').default;

Array of rows

API

each([parameters]).test(name, testFn)

each:

• parameters: Array of Arrays with the arguments that are passed into the testFn for each row
  • Note If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]]

.test:

• name: String the title of the test.
  • Generate unique test titles by positionally injecting parameters with printf formatting:
    • %p - pretty-format.
    • %s- String.
    • %d- Number.
    • %i - Integer.
    • %f - Floating point value.
    • %j - JSON.
    • %o - Object.
    • %# - Index of the test case.
    • %% - single percent sign ('%'). This does not consume an argument.
  • Or generate unique test titles by injecting properties of test case object with $variable
    • To inject nested object values use you can supply a keyPath i.e. $variable.path.to.value
    • You can use $# to inject the index of the test case
    • You cannot use $variable with the printf formatting except for %%
• testFn: Function the test logic, this is the function that will receive the parameters of each row as function arguments

each([parameters]).describe(name, suiteFn)

each:

• parameters: Array of Arrays with the arguments that are passed into the suiteFn for each row
  • Note If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]]

.describe:

• name: String the title of the describe
  • Generate unique test titles by positionally injecting parameters with printf formatting:
    • %p - pretty-format.
    • %s- String.
    • %d- Number.
    • %i - Integer.
    • %f - Floating point value.
    • %j - JSON.
    • %o - Object.
    • %# - Index of the test case.
    • %% - single percent sign ('%'). This does not consume an argument.
  • Or generate unique test titles by injecting properties of test case object with $variable
    • To inject nested object values use you can supply a keyPath i.e. $variable.path.to.value
    • You can use $# to inject the index of the test case
    • You cannot use $variable with the printf formatting except for %%
• suiteFn: Function the suite of test/its to be ran, this is the function that will receive the parameters in each row as function arguments

Usage

.test(name, fn)

Alias: .it(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).test('returns the result of adding %d to %d', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

each([
  {a: 1, b: 1, expected: 2},
  {a: 1, b: 2, expected: 3},
  {a: 2, b: 1, expected: 3},
]).test('returns the result of adding $a to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

.test.only(name, fn)

Aliases: .it.only(name, fn) or .fit(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).test.only('returns the result of adding %d to %d', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

.test.skip(name, fn)

Aliases: .it.skip(name, fn) or .xit(name, fn) or .xtest(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).test.skip('returns the result of adding %d to %d', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

.test.concurrent(name, fn)

Aliases: .it.concurrent(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).test.concurrent(
  'returns the result of adding %d to %d',
  (a, b, expected) => {
    expect(a + b).toBe(expected);
  },
);

.test.concurrent.only(name, fn)

Aliases: .it.concurrent.only(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).test.concurrent.only(
  'returns the result of adding %d to %d',
  (a, b, expected) => {
    expect(a + b).toBe(expected);
  },
);

.test.concurrent.skip(name, fn)

Aliases: .it.concurrent.skip(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).test.concurrent.skip(
  'returns the result of adding %d to %d',
  (a, b, expected) => {
    expect(a + b).toBe(expected);
  },
);

Asynchronous .test(name, fn(done))

Alias: .it(name, fn(done))

each([['hello'], ['mr'], ['spy']]).test(
  'gives 007 secret message: %s',
  (str, done) => {
    const asynchronousSpy = message => {
      expect(message).toBe(str);
      done();
    };
    callSomeAsynchronousFunction(asynchronousSpy)(str);
  },
);

.describe(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).describe('.add(%d, %d)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test('does not mutate first arg', () => {
    a + b;
    expect(a).toBe(a);
  });

  test('does not mutate second arg', () => {
    a + b;
    expect(b).toBe(b);
  });
});

each([
  {a: 1, b: 1, expected: 2},
  {a: 1, b: 2, expected: 3},
  {a: 2, b: 1, expected: 3},
]).describe('.add($a, $b)', ({a, b, expected}) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test('does not mutate first arg', () => {
    a + b;
    expect(a).toBe(a);
  });

  test('does not mutate second arg', () => {
    a + b;
    expect(b).toBe(b);
  });
});

.describe.only(name, fn)

Aliases: .fdescribe(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).describe.only('.add(%d, %d)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

.describe.skip(name, fn)

Aliases: .xdescribe(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).describe.skip('.add(%d, %d)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

---

Tagged Template Literal of rows

API

each[tagged template].test(name, suiteFn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.test('returns $expected when adding $a to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

each takes a tagged template string with:

• First row of variable name column headings separated with |
• One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.

.test:

• name: String the title of the test, use $variable in the name string to inject test values into the test title from the tagged template expressions
  • To inject nested object values use you can supply a keyPath i.e. $variable.path.to.value
  • You can use $# to inject the index of the table row.
• testFn: Function the test logic, this is the function that will receive the parameters of each row as function arguments

each[tagged template].describe(name, suiteFn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.describe('$a + $b', ({a, b, expected}) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test('does not mutate first arg', () => {
    a + b;
    expect(a).toBe(a);
  });

  test('does not mutate second arg', () => {
    a + b;
    expect(b).toBe(b);
  });
});

each takes a tagged template string with:

• First row of variable name column headings separated with |
• One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.

.describe:

• name: String the title of the test, use $variable in the name string to inject test values into the test title from the tagged template expressions
  • To inject nested object values use you can supply a keyPath i.e. $variable.path.to.value
• suiteFn: Function the suite of test/its to be ran, this is the function that will receive the parameters in each row as function arguments

Usage

.test(name, fn)

Alias: .it(name, fn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.test('returns $expected when adding $a to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

.test.only(name, fn)

Aliases: .it.only(name, fn) or .fit(name, fn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.test.only('returns $expected when adding $a to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

.test.skip(name, fn)

Aliases: .it.skip(name, fn) or .xit(name, fn) or .xtest(name, fn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.test.skip('returns $expected when adding $a to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

Asynchronous .test(name, fn(done))

Alias: .it(name, fn(done))

each`
  str
  ${'hello'}
  ${'mr'}
  ${'spy'}
`.test('gives 007 secret message: $str', ({str}, done) => {
  const asynchronousSpy = message => {
    expect(message).toBe(str);
    done();
  };
  callSomeAsynchronousFunction(asynchronousSpy)(str);
});

.describe(name, fn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.describe('$a + $b', ({a, b, expected}) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test('does not mutate first arg', () => {
    a + b;
    expect(a).toBe(a);
  });

  test('does not mutate second arg', () => {
    a + b;
    expect(b).toBe(b);
  });
});

.describe.only(name, fn)

Aliases: .fdescribe(name, fn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.describe.only('$a + $b', ({a, b, expected}) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

.describe.skip(name, fn)

Aliases: .xdescribe(name, fn)

each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`.describe.skip('$a + $b', ({a, b, expected}) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

License

MIT

Changelog

29.7.0

Features

• [create-jest] Add npm init / yarn create initialiser for Jest projects (#14465)
• [jest-validate] Allow deprecation warnings for unknown options (#14499)

Fixes

• [jest-resolver] Replace unmatched capture groups in moduleNameMapper with empty string instead of undefined (#14507)
• [jest-snapshot] Allow for strings as well as template literals in inline snapshots (#14465)
• [@jest/test-sequencer] Calculate test runtime if perStats.duration is missing (#14473)

Performance

• [@jest/create-cache-key-function] Cache access of NODE_ENV and BABEL_ENV (#14455)

Chore & Maintenance

• [jest-cli] Move internal config initialisation logic to the create-jest package (#14465)